home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 February / Macworld (1999-02).dmg / Shareware World / Shareware Feature / BBEdit Lite 4.1 / BBEdit Lite Quickstart.txt < prev    next >
Text File  |  1998-02-19  |  63KB  |  1,425 lines

  1. About BBEdit Lite
  2. ===== ====== ====
  3.  
  4. BBEdit Lite 4.1 is a freeware derivative of BBEdit 4.5, the popular and
  5. critically acclaimed text and HTML editor for Web authors, programmers,
  6. on-line-service users, and anyone else who needs to edit plain-text
  7. files.
  8.  
  9. BBEdit Lite is shipped with this QuickStart document which describes
  10. many of the application's features. Please note that this file is the
  11. only documentation available for BBEdit Lite. Full documentation, as
  12. well as a considerable amount of additional functionality, is available
  13. with the purchase of BBEdit 4.5. See the document "How do I order BBEdit
  14. 4.5" for details on obtaining your own copy of BBEdit.
  15.  
  16. We are committed to providing continued support for BBEdit Lite by
  17. responding to individual questions and inquiries, as well as in
  18. providing fixes for Lite, and improvements in its functionality. We will
  19. announce any future changes or updates to Lite via the comp.sys.mac.*
  20. newsgroups, as well as by providing information and downloadable
  21. versions on our Web and ftp sites. We regret that we cannot offer
  22. telephone or fax support for BBEdit Lite; if you have any suggestions,
  23. comments, or questions regarding Lite, please send us email at
  24. <support@barebones.com>.
  25.  
  26.  
  27. Overview
  28. ========
  29.  
  30. BBEdit Lite Capabilities
  31. ------ ---- ------------
  32.  
  33. BBEdit Lite offers a great deal of useful functionality:
  34.  
  35. *   Powerful multi-file search. BBEdit Lite offers the usual multi-file
  36.     search, in which a disk directory is scanned and the files are
  37.     opened one at a time; however, BBEdit Lite can also display the
  38.     search results in a window for easy browsing (and selected entries
  39.     in the window can be opened for display). The search can also be
  40.     limited to files that are already opened for editing, or to files
  41.     which were already found in a previous multi-file search. BBEdit
  42.     Lite also offers multi-file replace capability for automated "search
  43.     and destroy" operations.
  44.  
  45. *   File size limited only by available memory. BBEdit Lite's default
  46.     partition size is 1221K (only 650K with VM or RAMDoubler) of RAM.
  47.     This can be set as low as 450K, to make BBEdit Lite the ideal
  48.     constantly-resident editor for small to moderate tasks, or turned up
  49.     as high as necessary to edit many large files or perform large-scale
  50.     search-and-replace operations. BBEdit Lite automatically takes
  51.     advantage of available system memory, so that you don't have to
  52.     adjust its partition size to edit large files.
  53.  
  54. *   No hard limit on number of files open. The number of files that
  55.     BBEdit Lite can have open at once is limited by available memory,
  56.     and can be increased or decreased by adjusting  BBEdit Lite's
  57.     partition size as appropriate.
  58.  
  59. *   Easy manipulation of multiple files at once. The "Open Several..."
  60.     command makes it possible to open multiple files from different
  61.     folders at once, and the Save and Print commands can operate on all
  62.     open files at once.
  63.  
  64. *   Pattern ("grep") searching. Matching patterns can be constructed so
  65.     that strings other than exact literal matches can be found and
  66.     replaced; for example, converting Pascal comments to C comments, or
  67.     modifying instances of HTML tags.
  68.  
  69. *   Drag & Drop Editing. BBEdit Lite now includes support for Macintosh
  70.     Drag & Drop, both for internal editing operations, and for
  71.     exchanging data with other applications, or creating text clippings
  72.     in the Finder.
  73.  
  74. *   High performance. BBEdit Lite 4.1 includes PowerMac native code
  75.     support. Try and enjoy.
  76.  
  77. BBEdit Lite also offers the following significant benefits:
  78.  
  79. *   High quality. BBEdit Lite is based on mature and stable technology;
  80.     this technology is the beneficiary of years of in-house and field
  81.     use and testing. The commitment to quality and functionality shown
  82.     in BBEdit 4.5 is reflected in BBEdit Lite.
  83.  
  84. *   Zero cost. BBEdit Lite is free, with no qualification. It is not a
  85.     shareware or commercial product. It is not a demo version, and there
  86.     is no expectation that you will buy anything.
  87.  
  88. *   Extensibility. BBEdit Lite can use plug-in code modules to perform
  89.     a wide range of text editing and transformation tasks. There are a
  90.     large number of these plug-ins already available from us, and from
  91.     other sources such as the Info-Mac archives.
  92.  
  93. This document contains specific information on how to take advantage of
  94. BBEdit Lite's capabilities. If you would like to write such plug-ins, we
  95. offer a BBEdit extension developer's kit, which includes documentation
  96. on how to write your own plug-ins, as well as source code for several
  97. sample plug-ins. A copy of the BBEdit Extension SDK is available from
  98. our Web site:
  99.  
  100. <http://web.barebones.com/updates.html>
  101.  
  102. or from our FTP site:
  103.  
  104. <ftp://ftp.barebones.com/>
  105.  
  106. as well as from Info-Mac mirror sites, in the /info-mac/text/bb directory.
  107.  
  108. Differences between BBEdit Lite and BBEdit 4.5
  109. ----------- ------- ------ ---- --- ------ ---
  110.  
  111. BBEdit Lite has many of the same capabilities as the commercial BBEdit;
  112. however, the following capabilities of the commercial BBEdit are -not-
  113. present in BBEdit Lite:
  114.  
  115. *   BBEdit Lite cannot use the advanced HTML markup tools that are
  116.     supplied with the full version;
  117.  
  118. *    BBEdit Lite does not include syntax coloring support;
  119.  
  120. *   BBEdit Lite does not support Internet Config for interacting 
  121.     directly with Internet service applications (such as Web browsers and FTP clients);
  122.  
  123. *   BBEdit Lite is not scriptable;
  124.  
  125. *    BBEdit Lite does not have an integrated FTP tool for accessing
  126.     and editing files directly;
  127.  
  128. *   BBEdit Lite does not include an integrated spelling checker;
  129.  
  130. *   BBEdit Lite has only 1 level of Undo capability;
  131.  
  132. *   BBEdit Lite's use of Macintosh Drag and Drop is limited to dragging
  133.     and dropping of text while editing. Commercial versions of BBEdit
  134.     make more comprehensive use of drag-and-drop operations.
  135.  
  136. *   Find Differences (comparing files, folders, and projects) is not
  137.     included;
  138.  
  139. *   QuickSearch (an incremental search facility) is not provided;
  140.  
  141. *   There is no option for split windows
  142.  
  143. *   Disk browsers are not available, and you can only have one Search
  144.     Results window open at a time;
  145.  
  146. *   BBEdit's advanced PopupFuncs(TM) technology is not built in (you can,
  147.     however, obtain and install PopupFuncs 2.8 or later into BBEdit
  148.     Lite);
  149.  
  150. *   BBEdit Lite cannot open or browse project documents;
  151.  
  152. *   Integration with THINK C, Symantec C++, CodeWarrior, and THINK
  153.     Reference is not supported;
  154.  
  155. *   ToolServer is not supported;
  156.  
  157. *   The Glossary function is not supported;
  158.  
  159. *   Marker support is not provided;
  160.  
  161. *   BBEdit Lite does not support Apple Guide for active assistance in
  162.     using its capabilities.
  163.  
  164. *   XTND translation is not supported;
  165.  
  166. In addition to the specific capabilities listed here, BBEdit 4.5
  167. contains a large number of refinements and smaller capabilities that 
  168. are not present in BBEdit Lite.
  169.  
  170.  
  171. About BBEdit 4.5
  172. ----- ------ ---
  173.  
  174. BBEdit 4.5 is an industrial-strength text editor for use by software
  175. developers, HTML authors, engineers, scientists, telecommunications
  176. users, and anyone else who needs to view, edit and manipulate plain-text
  177. documents with maximum flexibility and performance. BBEdit 4.5 is an
  178. ideal companion for CodeWarrior, THINK C, Symantec C++, THINK Pascal,
  179. MPW, and THINK Reference users. With BBEdit 4.5, you can:
  180.  
  181. *   Take advantage of integrated HTML editing tools and integration
  182.     with Internet services to create and edit World Wide Web content;
  183.  
  184. *    See your code in color, with BBEdit's built-in syntax coloring for 
  185.     HTML, Java, Perl, C, C++, Pascal, and a whole bunch of other languages;
  186.  
  187. *   Quickly and easily edit files residing on remote FTP file servers, 
  188.     via "Open from FTP" and "Save to FTP" commands;
  189.  
  190. *   Use an integrated HTML-aware spell checker with a 100,000+ word
  191.     dictionary to correct typographical and spelling errors;
  192.  
  193. *   Automate operations via AppleScript, Frontier, or any other
  194.     OSA- compliant scripting system;
  195.  
  196. *   Easily compare text files, folders, and projects via a built-in
  197.     differences engine and browser;
  198.  
  199. *   Use BBEdit 4.5 in conjunction with Metrowerks CodeWarrior (version
  200.     1.2 or later required) to compile source files, and run and debug
  201.     projects;
  202.  
  203. *   Access multiple levels of Undo to speed your content editing tasks;
  204.  
  205. *   Use Macintosh Drag and Drop (included) for text editing and in
  206.     various parts of the user interface;
  207.  
  208. *   Use integrated PopupFuncs(TM) technology to quickly navigate C, C++,
  209.     Java, Pascal, Fortran, 68K assembler, Perl, HTML, Tcl, GuideScript,
  210.     TeX, and ScriptX source files;
  211.  
  212. *   Browse and search source files in CodeWarrior, THINK C/Symantec
  213.     C++, and THINK Pascal project documents;
  214.  
  215. *   Use BBEdit 4.5 in conjunction with Symantec C++ (version 6.0 or
  216.     later required) to compile source files and run projects;
  217.  
  218. *   Use ToolServer to execute MPW Shell scripts for building MPW-based
  219.     applications and other MPW-driven tasks, as well as MPW 411-based
  220.     Toolbox searches;
  221.  
  222. *   Use THINK Reference 2.0, MPW 411, or Macintosh Programmer's Toolbox
  223.     Assistant to search for Toolbox symbols and insert Toolbox call
  224.     templates;
  225.  
  226. *   Open disk browser windows to easily navigate the directory
  227.     structures of any mounted volumes and view files quickly and easily;
  228.  
  229. *   Take advantage of integrated Claris XTND translation to translate
  230.     text files to and from popular word processor formats;
  231.  
  232. *   Use a glossary to store commonly-used pieces of text for insertion
  233.     with a single keystroke;
  234.  
  235. *   Split editing windows for easier navigation and reference;
  236.  
  237. *   Enjoy many other technical advancements and refinements made since
  238.     the original release of BBEdit.
  239.  
  240. In addition, BBEdit 4.5 is delivered on CD-ROM with full printed and
  241. electronic documentation, a complete collection of BBEdit plug-ins
  242. contributed by BBEdit users from all over the world, demo versions of
  243. ours and other developers' products, and product information and special
  244. offers from select third-party developers. (Customers who don't have a
  245. CD-ROM drive can obtain floppy disks at a nominal extra cost.)
  246.  
  247. Additional information on BBEdit 4.5's capabilities, and instructions on
  248. how to upgrade, are contained in the enclosed documents "What is BBEdit
  249. 4.5" and "How do I order BBEdit 4.5", or you can visit our Web site:
  250.  
  251.     <http://www.barebones.com/>
  252.  
  253. for the latest information available.
  254.  
  255.  
  256. Distribution
  257. ============
  258.  
  259. BBEdit Lite is Freeware
  260. ------ ---- -- --------
  261.  
  262. BBEdit Lite is a freely distributable, copyrighted program, otherwise
  263. known as "freeware". There is no registration process, no fee requested
  264. or required, no obligation on your part, and no guilt.
  265.  
  266. We at Bare Bones Software do not produce or develop "shareware"; it has
  267. been our direct experience that many people simply ignore shareware
  268. notices. The cost of goods related to distributing BBEdit Lite is very
  269. low, and can be recouped by means other than (unsuccessfully) trying to
  270. shame users into paying some small amount of money for a program.
  271.  
  272. We believe that when users of a program make the financial sacrifice to
  273. obtain a piece of software, they should expect, and receive, significant
  274. value added. This is why a commercial distribution of BBEdit exists.
  275.  
  276. If you feel compelled to pay us for BBEdit Lite, don't. If you need the
  277. capabilities that the commercial version of BBEdit has to offer, we
  278. encourage you to order your own copy of BBEdit. See "How do I order
  279. BBEdit 4.5" for information on how to do it.
  280.  
  281.  
  282. License Requirements
  283. ------- ------------
  284.  
  285. Although BBEdit Lite is free, it is not "public domain". It is a
  286. copyrighted software program, and Bare Bones Software, Inc. reserves all
  287. rights; therefore:
  288.  
  289. *   BBEdit Lite cannot be sold, either by itself or in combination with
  290.     any other product, without the express written permission of Bare
  291.     Bones Software, Inc.
  292.  
  293. *   If you are a user group which is publishing a CD-ROM or floppy
  294.     collection, you may include BBEdit Lite and all of its related files
  295.     without restriction, save that the entire original package is
  296.     included. Contact Bare Bones Software for up-to-date versions and
  297.     information.
  298.  
  299. *   If you are a hard disk vendor which distributes PD, shareware, and
  300.     freeware on your disk drives, you are welcome to distribute BBEdit
  301.     Lite. Contact Bare Bones Software for up-to-date versions and
  302.     information.
  303.  
  304. *   Commercial publishers and distributors of CD-ROM software
  305.     collections, to include any and all software compilations provided
  306.     as an adjunct to printed or online publications, may not distribute
  307.     BBEdit Lite on CD-ROM without the express written permission of Bare
  308.     Bones Software, Inc.
  309.  
  310. *   BBEdit Lite may be posted on an information service which charges
  311.     its users for general connection time and downloading, but it may
  312.     NOT be posted to an information service which will charge for the
  313.     specific right to download BBEdit Lite, without the express written
  314.     permission of Bare Bones Software, Inc.
  315.  
  316. *   BBEdit Lite may be given away as a support utility for a package
  317.     which is itself to be given away. People who need to distribute
  318.     BBEdit Lite as a support utility should contact Bare Bones Software
  319.     for up-to-date versions and information.
  320.  
  321. Address all correspondence to:
  322.  
  323. Postal: Bare Bones Software, Inc.
  324.         P.O. Box 1048
  325.         Bedford, MA 01730
  326.  
  327. Web:    <http://www.barebones.com/>
  328.  
  329. email:  <sales@barebones.com>   -- licensing inquiries only
  330.  
  331.         <support@barebones.com> -- all technical questions
  332.  
  333. Phone:  +1 781 687-0700
  334. Fax:    +1 781-687-0711
  335.  
  336. Please note that we cannot provide technical support for BBEdit Lite or our 
  337. other freeware products via phone or fax.
  338.  
  339.  
  340. Getting Started with BBEdit Lite
  341. ======= ======= ==== ====== ====
  342.  
  343. Installation
  344. ------------
  345. BBEdit Lite consists of the following major components:
  346.  
  347. *   The BBEdit Lite application itself 
  348.  
  349. *   The "BBEdit Plug-ins" folder, which contains plug-in code modules
  350.     that can provide specialized text processing or utility functions
  351.  
  352. Only the BBEdit Lite application file is required in order to run and
  353. use BBEdit Lite; you do not need to have any plug-ins.
  354.  
  355. If you are planning to install the whole set of BBEdit Lite files,
  356. create a "BBEdit Lite Folder". Then, copy the application and the
  357. "BBEdit Plug-ins" folder into your BBEdit Lite Folder.
  358.  
  359. Creating and Saving Documents
  360. -------- --- ------ ---------
  361. To create a new document within BBEdit Lite, choose "New" from the File
  362. menu. An empty editing window will be opened on the screen. You can type
  363. in this window, paste text from another document or application, or do
  364. anything else which causes text to be placed in this window.
  365.  
  366. Please note that in BBEdit Lite 4.1, the various "New" commands (which
  367. were previously hidden on the File menu) have been gathered into a
  368. single "New" submenu. However, your reflexes will still produce the
  369. expected results: Command-N still creates a new editing window, and you
  370. can still choose the first command from the File menu to create a new
  371. editing window.
  372.  
  373. Once you have opened a new window and done some basic editing, you can
  374. save your new document. To do this, choose the "Save As..." command from
  375. the File menu. Type in the name of your new file and click on "Save".
  376.  
  377. Editing Documents
  378. ------- ---------
  379. In terms of its basic editing functionality, BBEdit Lite behaves like
  380. any other word processor or text editor on the Macintosh: any typed
  381. characters are inserted at the insertion point; if there is a selection
  382. present, the selection is replaced by the first typed character, and the
  383. insertion point is placed after the first typed character.
  384.  
  385. The insertion point is indicated by a blinking vertical bar.
  386.  
  387. If there is any text selected in the active (or front) window, it is
  388. highlighted using your Mac's default highlight color. If there is text
  389. selected in a window that is inactive (not the front window), it is
  390. framed in the highlight color.
  391.  
  392. As you type, BBEdit Lite scrolls the window's contents so that the insertion 
  393. point is visible. Unless you have the "Soft Wrap Text" option selected, the 
  394. window may scroll horizontally as you type.
  395.  
  396. To move text from one place to another, select the text you wish to
  397. move, and choose the "Cut" command from the Edit menu. The selected text
  398. will be deleted, and placed in a special area called the "Clipboard".
  399. (The Clipboard always contains the last text that you cut or copied.)
  400. You can then use the "Paste" command on the Edit menu to place the text
  401. elsewhere in the document you are editing, or even in another window
  402. altogether. Also, any text that you cut or copy can be pasted into
  403. another application. You can place text in the Clipboard without
  404. deleting it by choosing "Copy" from the Edit menu.
  405.  
  406. When you Paste, the text that's in the Clipboard will replace the
  407. current selection (if there is one), or be inserted at the insertion
  408. point. Paste doesn't remove text from the Clipboard, so you can Paste as
  409. many times as you wish.
  410.  
  411. To delete selected text, hit the "Delete" key on your keyboard, or
  412. choose "Clear" from the Edit menu. If you have a keyboard with a numeric
  413. keypad on it, you can hit the "Clear" key on the keypad to delete the
  414. selected text.
  415.  
  416. To select all the text in the front editing window, choose "Select All"
  417. from the Edit menu. You can then cut, copy, or perform any other action
  418. that affects selected text.
  419.  
  420. BBEdit Lite provides an assortment of facilities for transforming text
  421. in various ways. The commands to transform text are all found under the
  422. Text menu:
  423.  
  424. Balance locates the pair of parentheses, braces, or brackets which
  425.     encloses the current selection range or insertion point. If there
  426.     are unmatched parentheses, braces, or brackets, BBEdit Lite will
  427.     beep.
  428.  
  429. Twiddle transposes the two characters on either side of the insertion
  430.     point, or at either end of the selected text.
  431.  
  432. Change Case... allows you to automatically switch between upper and
  433.     lower case characters for entire words, first letters of words, or
  434.     first letters of lines.
  435.  
  436. Shift Right and Shift Left will indent the selected text by one tab stop
  437.     (in the case of Shift Right), or outdent by one tab stop (for Shift
  438.     Left). If you hold down the Shift key while choosing one of these
  439.     commands, the selected text will be indented or outdented by one
  440.     space instead of one tab stop.
  441.  
  442. The Hard Wrap... command is used for wrapping long lines of text and
  443.     filling paragraphs. Essentially, it uses carriage returns to break
  444.     lines of text, to keep them from running off to the right of your
  445.     screen.
  446.  
  447. Insert Line Breaks "freezes" the line breaks in soft-wrapped documents,
  448.     by turning each soft line break into a hard carriage return. This is
  449.     useful when preparing to transmit a soft-wrapped document to an
  450.     environment that doesn't support soft wrapping.
  451.  
  452. Remove Line Breaks removes carriage returns and spaces between groups of
  453.     text. Essentially, it performs the reverse function of the "Hard
  454.     Wrap..." command.
  455.  
  456. Zap Gremlins... is useful for finding and altering non-printing
  457.     characters in your text files.
  458.  
  459. Entab converts runs of spaces into tabs, according to the current
  460.     setting in the "Font and Tabs..." dialog. This transformation is
  461.     useful when downloading text from a mainframe computer or on-line
  462.     service which uses spaces to line up columns of text; when
  463.     displaying the text in a monospaced font, columns will still usually
  464.     not line up unless you Entab the text.
  465.  
  466. Detab converts tabs into runs of spaces, according to the current
  467.     setting in the "Font and Tabs..." dialog. This is useful when
  468.     uploading text to a mainframe or on-line service which has no
  469.     concept of tabs as column separators.
  470.  
  471. Cursor Key Equivalents
  472.  
  473. Sometimes, you may want to perform word selection or deletions directly 
  474. from the keyboard. Here are some available shortcuts:
  475.  
  476. Key                 Modifier        Action
  477. ===                 ========        ======
  478. (left/right) Arrow  (none)          Move 1 character left/right
  479.  
  480. (left/right) Arrow  Option          Move 1 word left/right
  481.  
  482. (left/right) Arrow  Command         Move to beginning/end of line
  483.  
  484. (up/down) Arrow     (none)          Move up/down 1 line in file
  485.  
  486. (up/down) Arrow     Command         Move to top/bottom of file
  487.  
  488. (up/down) Arrow     Option          Move to previous/next screen page
  489.  
  490. [any of the above]  Shift           Make or extend a selection range
  491.  
  492. Delete              (none)          Deletes selection range, or 
  493.                                     character preceding the insertion point.
  494.  
  495. Delete              (Command)       Deletes all characters backwards 
  496.                                     to beginning of line
  497.  
  498. Delete              (Option)        Deletes all characters back to
  499.                                     beginning of word
  500.                                         
  501. There is an option to "Exchange Command & Option" key effects in the
  502. Editor section of the Preferences, for those who may be used to some
  503. older environments which behaved this way. If this option is activated,
  504. the behavior of the Up and Down arrow key equivalents will change
  505. accordingly.
  506.  
  507.  
  508. Menu Item Modifiers
  509. ---- ---- ---------
  510. Here is a listing of some of the additional functions (or changes to the
  511. behavior of existing functions) which can be invoked by using various
  512. modifier keys. Please remember that BBEdit Lite displays the modified
  513. names of these commands in its menus, so to see the commands in context,
  514. just pull down the menu and press one or more modifier keys.
  515.  
  516.  
  517. Menu    Item            Modifier    New Name            Action
  518. ====    ====            ========    === ====            ======
  519. File    Open Selection  Option      Reveal Selection    Displays the selected
  520.                                                         file in the Finder
  521.                                                         
  522.         Close           Option      Close All           Closes all
  523.                                                         open documents
  524.  
  525.         Save            Option      Save All            Saves all unsaved
  526.                                                         documents
  527.  
  528.         Save As..       Option      Save As Selection.. Uses selection
  529.                                                         as default name
  530.                                                         for Save As
  531.  
  532.         Print..         Option      Print All..         Prints all open
  533.                                                         documents
  534.  
  535.         Quit..          Option      Transfer..          Run another
  536.                                                         application
  537.  
  538. Edit    Cut             Shift       Cut & Append        Cut & Add to
  539.                                                         Clipboard
  540.  
  541.         Copy            Shift       Copy & Append       Add to Clipboard
  542.  
  543.         Select Line     Option      Select Paragraph    Selects paragraph
  544.                                                         containing current
  545.                                                         line
  546.                                                         
  547. Text    Twiddle         Option      Twiddle Words       Exchange words
  548.  
  549.         Change Case..   Option      Change Case         Use current
  550.                                                         settings
  551.  
  552.         Shift Left      Shift       Shift Left One Space
  553.  
  554.         Shift Right     Shift       Shift Right One Space   
  555.     
  556.         Wrap..          Option      Wrap                Wrap with
  557.                                                         current settings
  558.  
  559.         Unwrap..        Option      Unwrap              Unwrap with
  560.                                                         current settings
  561.  
  562.         Zap "Gremlins"..Option      Zap "Gremlins"      Zap with
  563.                                                         current settings
  564.  
  565.         Entab..         Option      Entab               Use current
  566.                                                         settings
  567.  
  568.         Detab..         Option      Detab               Use current
  569.                                                         settings
  570.     
  571. Search  Enter           Option      Enter
  572.         Search String               Replace String
  573.  
  574.         Find in         Option      Open All Matches    Find in Next File
  575.         Next File                                       until no more found
  576.  
  577.         Go to Line...     Option      Go to Line          Use last setting
  578.  
  579. Windows Arrange...        Option      Arrange             Use last setting
  580.  
  581.  
  582.  
  583. Special Keys
  584. ------- ----
  585. The Apple Extended Keyboard has additional function keys on it, which are
  586. usable within BBEdit Lite:
  587.  
  588. Key             Action
  589. ===             ======
  590. F1              Undo
  591. F2              Cut
  592. F3              Copy
  593. F4              Paste
  594. "del"           Forward Delete
  595. Home/End        Scroll to start/end of document
  596. Cmd-Home/End    Move insertion point to start/end of document
  597. Page Up/Down    Scroll up/down a page
  598.     
  599.  
  600. Printing
  601. --------
  602. BBEdit Lite offers a variety of options for varying your printed output.
  603. These options are available from the dialog that appears when you choose
  604. "Print" from the File menu.
  605.  
  606. If you are using recent versions of the LaserWriter driver, select the
  607. "BBEdit Lite 4.1" item from the popup menu to access these options. If
  608. you are using an older version of the LaserWriter drivers, or other
  609. printer drivers,  the portion of the dialog above the gray line is the
  610. normal set of controls that is provided by whichever printer driver you
  611. use. Below the gray line are controls provided specifically by BBEdit
  612. Lite.
  613.  
  614. *   The "Printing Font:" button will bring up a dialog that allows you
  615.     to set the font, size, style, and tab attributes for the text when
  616.     it's printed (as opposed to when it's displayed). For a description
  617.     of the controls in this dialog, see the "Editing" section of this
  618.     document.
  619.  
  620. *   The "Options..." button will present a dialog box for setting
  621.     various formatting options, most of which should be
  622.     self-explanatory.
  623.  
  624. Most of the options in "Options..." dialog only affect the appearance of
  625. the pages that are printed out, and can therefore be set according to
  626. your individual taste.
  627.  
  628.  
  629. Setting Your Preferences 
  630. ------- ---- -----------
  631. To bring up the Preferences dialog, choose "Preferences..." from the
  632. Edit menu, or double-click on your BBEdit Lite Prefs file. (This may not
  633. be convenient, since the BBEdit Lite Prefs file usually resides
  634. somewhere within the System Folder.)
  635.  
  636. The list on the left-hand side of the dialog determines which section of
  637. the preferences you are looking at. If you click on "Save", all of the
  638. preferences settings will be saved to the "BBEdit Lite Prefs" file. If
  639. you click on "Cancel", the existing preferences will be left alone, and
  640. any changes you've made in the Preferences settings will be discarded.
  641.  
  642. The Editor preferences control BBEdit Lite's editing and keyboard
  643. behavior. These settings establish the defaults for newly-created
  644. documents, as well as for text files that don't already contain BBEdit
  645. Lite state information.
  646.  
  647. *   The "Default Font" button sets the font which will be used to
  648.     display the text in newly created windows, and for documents which
  649.     have no saved state information.
  650.  
  651. *   If "Auto-Indent" is turned on, BBEdit Lite will indent to the start
  652.     of the preceding line whenever you type the "Return" key on the
  653.     keyboard. This is useful for programmers and for reverse-indenting
  654.     text. It may be less convenient if you are using BBEdit Lite for
  655.     composing prose.
  656.  
  657. *    Soft Wrap Text: by default, BBEdit Lite does not automatically wrap
  658.     text as you type it in, which means the text may scroll
  659.     horizontally. Selecting this option tells BBEdit Lite to wrap the
  660.     text as you enter, insert, or delete it, using the "Wrap To:" width
  661.     that you choose.
  662.  
  663. *   If Balance While Typing is turned on, BBEdit Lite will flash
  664.     matching parentheses, curly braces, and brackets as you type them.
  665.  
  666. *   Smart Quotes is used to determine the default value of the Smart
  667.     Quotes setting for newly created windows and for documents saved
  668.     with state information other than "BBEdit". If this option is on,
  669.     BBEdit Lite will automatically insert curly, or typographers, quotes
  670.     instead of the normal straight marks. (If you are editing material
  671.     for online distribution, or platforms other than Mac, it is best to
  672.     leave this off!)
  673.  
  674. *   Ordinarily, actions such as using BBEdit plug-ins are not undoable,
  675.     and BBEdit Lite will alert you if you are about to perform a
  676.     non-undoable action. If you are not concerned about being able to
  677.     undo these actions, and do not want BBEdit Lite to alert you, turn
  678.     on the "No 'Can't Undo' Alerts" check box.
  679.  
  680. *   Exchange Command and Option reverses the meaning of the Command and
  681.     Option keys when used with the Up and Down arrow keys. See
  682.     "Editing Text with BBEdit Lite" for more details.
  683.  
  684. *   If Use Keypad for Cursor Control is checked, the keys on the
  685.     numeric keypad (on keyboards that have them) will move the cursor.
  686.     See "Editing Text With BBEdit Lite" for more details.
  687.  
  688.  
  689. The File Search section of the Preferences controls BBEdit Lite's
  690. behavior when searching for files via the "Open Selection" command.
  691.  
  692. *   If "Skip (...) Folders" is checked, BBEdit Lite will ignore folders
  693.     whose names are enclosed in parentheses.
  694.  
  695. *   The "Default <...> Directory" setting determines which directory 
  696.     BBEdit Lite will start a multi-file search in by default (if you
  697.     do not select another folder from the Find dialog).
  698.  
  699. *   If "Follow Aliases" is checked, BBEdit Lite will resolve any folder
  700.     aliases it encounters during its search.
  701.  
  702. The File Types section of the Preferences allows you to modify the list
  703. of file creators that appears in the "File Creator" popup menu of the
  704. "Save As..., Options..." dialog box.
  705.  
  706. To add a new application's file creator to the list, click the "Add..."
  707. button, and choose the application. To change an application's creator
  708. signature, click on an application name in the list, enter a new
  709. four-letter code in the text field next to "Creator...", and click the
  710. "Change" button. You can use the "Set button to pick an application and
  711. enter its creator code in the text field for you. To remove an
  712. application creator from the list, click on an application name, and
  713. click the "Delete" button.
  714.  
  715. The creators for "BBEdit Lite" and "Generic Text File" are built into
  716. BBEdit Lite and cannot be changed or deleted.
  717.  
  718. The Filing settings control the default settings for the Open... and
  719. Open Several... dialogs.
  720.  
  721. *   If "Wrap TeachText Files" is checked, then BBEdit Lite will always
  722.     soft- wrap files which have been created by TeachText (or its
  723.     successor SimpleText).
  724.  
  725. *   If "Auto-Backup" is checked, a backup will automatically be made of
  726.     a file every time it is saved.
  727.  
  728. The Grep Patterns section of the Preferences dialog allows you to modify
  729. the list of regular expressions which appears in the popup menu next to
  730. the "Grep" check box in the "Find..." dialog.
  731.  
  732. The scrolling list box shows the names of the installed patterns. When
  733. you click on one, the text fields below the list will be filled in with
  734. its name, search pattern, and replace pattern. You can change any of
  735. these text fields, and click "Change" to replace the selected pattern
  736. with the changed one. You can also enter new information in the text
  737. fields and click "Add" to add a new pattern, or select a pattern and
  738. click "Delete" to remove it from the list. For more information on grep
  739. patterns, please see the next section on Searching.
  740.  
  741. Note: You can install a pattern with an empty replace pattern, which is
  742. useful just for locating text which matches a particular regular
  743. expression.
  744.  
  745.  
  746. The Printing settings provide the default print settings for new windows
  747. and for documents which have saved state information other than BBEdit
  748. Lite's.
  749.  
  750. These settings correspond to the same settings on the "Options..."
  751. dialog which can be brought up from the Print... dialog.
  752.  
  753. The Search Folders section presents a list of folders which will appear
  754. in the "Folder:" pop-up menu in the "Find" dialog.
  755.  
  756. The Startup settings determine BBEdit Lite's behavior when it is
  757. launched without any documents.
  758.  
  759. *   The "At Startup:" radio buttons control what BBEdit Lite does when
  760.     it's launched by some means other than double-clicking on a BBEdit
  761.     Lite document, or by dragging and dropping some item onto BBEdit
  762.     Lite itself (under System 7).
  763.  
  764. *   If "Nothing" is selected, BBEdit Lite will take no action at
  765.     startup. This is handy if BBEdit Lite regularly gets launched into
  766.     the background, or is launched by some external utility which will
  767.     then start sending commands to BBEdit Lite directly.
  768.  
  769. *   New Window causes BBEdit Lite to bring up a new untitled window, as
  770.     if the "New command on the File menu had been chosen.
  771.  
  772. *   Open causes BBEdit Lite to bring up an "Open..." dialog, as if the
  773.     "Open..." command on the File menu had been chosen.
  774.  
  775. *   Open Several causes BBEdit Lite to bring up the "Open Several..."
  776.     dialog, as if that command had been chosen.
  777.  
  778. The State settings control what parts of a file's saved state are honored 
  779. whenever a file with saved state information is opened. In some cases, it 
  780. may be desirable to ignore one of these aspects of the saved state.
  781.  
  782. *   The "Remember File State" setting establishes whether BBEdit Lite
  783.     will remember information about the document's state (window
  784.     position, font and size settings, and other options). This default
  785.     is applied to newly created documents. If "Always Add State" is
  786.     checked, BBEdit Lite will remember state information for documents
  787.     that you open which don't already have saved state information.
  788.  
  789. The Text Search settings provide the defaults for text searching and
  790. multi-file searching. The options in this dialog correspond to their
  791. counterparts in the Find... and the Multi-File Search Options dialog.
  792.  
  793. The Windows settings affect the appearance and behavior of BBEdit Lite's 
  794. document windows.
  795.  
  796. *   Delay When Scrolling makes BBEdit Lite wait a tenth of a second when
  797.     you click in the arrows of a scrollbar before scrolling the text in
  798.     a document window.
  799.  
  800. *   Show Status Bar causes the status bar to be visible within all
  801.     editing windows. (See "Editing Text With BBEdit Lite" for a
  802.     description of the status bar.) This option is on by default; you
  803.     can turn it off if you have a small screen and screen "real estate"
  804.     is at a premium.
  805.  
  806. *   Show Philip Bar draws a vertical gray line in the status bar at the
  807.     point where the visible editing area ends on a 9-inch "classic"
  808.     screen.
  809.  
  810. *   Show Tab Stops places tick marks in the status bar to indicate the
  811.     position of tab stops in each editing window. This option is dimmed
  812.     if "Show Status Bar" is turned off.
  813.  
  814. *   Show Line Numbers places line numbers along the left edge of each
  815.     editing window.
  816.  
  817. *   Show Cursor Position places the cursor-position display at the
  818.     lower left corner of each editing window; this display shows the
  819.     position of the insertion point, or the last-changed end of the
  820.     selection range.
  821.  
  822. *   Window Zooming controls the maximum width to which BBEdit Lite will
  823.     open documents, either by default or when using the zoom-box control
  824.     in the upper right-hand corner of the window; the "Zoom Windows To"
  825.     setting determines where BBEdit Lite will place windows that are
  826.     zoomed on multiple-screen systems.
  827.  
  828. *   If either of the check boxes under the "Leave Room for Finder" is
  829.     checked, BBEdit Lite will make certain that there's enough space
  830.     below and/or to the right of any window so that icons on the desktop
  831.     are not obscured by the edges of the Window.
  832.  
  833. Note:  If you are running on a Macintosh with a 9-inch screen, the
  834. window sizes when either of these options is checked are usually too
  835. small to be useful. Therefore, you may want to turn these options off if
  836. you have a small screen.
  837.  
  838.  
  839. Text Wrapping
  840. ---- --------
  841.  
  842. BBEdit Lite offers the capability to wrap text in a variety of ways. One
  843. method of wrapping is the "soft" or "live" word wrapping that
  844. word-processors provide;  it is useful when importing text files from
  845. word processors or other programs that do not use carriage returns to
  846. break lines on the screen. When opened, such files appear to have only a
  847. few lines in them, which run far past the right-hand edge of the window.
  848. Soft text wrapping is also useful when you are writing text that will be
  849. exported to a word processor or page-layout program, as well as in other
  850. situations in which paragraphs are separated by carriage returns.
  851.  
  852. For composing text in situations where carriage returns are a line
  853. separator (rather than a paragraph separator), "hard" text wrapping is
  854. useful for formatting your text.
  855.  
  856. To hard-wrap text in the current document window, choose "Hard Wrap..."
  857. from the Text menu.
  858.  
  859. The controls on the left half of the "Hard Wrap..." dialog box control
  860. how much of the text is wrapped, and the maximum length of the lines
  861. after wrapping.
  862.  
  863. The group of radio buttons controls the length of lines after they have
  864. been wrapped:
  865.  
  866. *   The "Philip Bar" button will break lines of text at the philip bar.
  867.     (To see the location of the philip bar, turn on "Show Philip Bar" in
  868.     the Windows section of the Preferences dialog.) The philip bar
  869.     indicates the maximum usable width of a document window when the
  870.     window is zoomed to full size on a nine-inch "classic" Macintosh
  871.     screen. For this reason, you are guaranteed that text wrapped to the
  872.     philip bar will be readable without horizontal scrolling by anyone
  873.     on any Macintosh.
  874.  
  875. *   If "Window Width" is selected, no wrapped line will be longer than
  876.     the current width of the window. This option is useful if you'd like
  877.     the lines to be a little longer or a little shorter than is provided
  878.     for by the philip bar; just size the window appropriately and wrap.
  879.  
  880. *   If "Character Width" is selected, the number in the text field
  881.     designates the maximum number of characters allowed on any line; a
  882.     line that exceeds this number of characters in length will be
  883.     wrapped. The "Character Width" setting is useful for preparing
  884.     postings to on-line services, which can break lines in an
  885.     unattractive fashion if they're longer than a fixed number of
  886.     characters (usually 80).
  887.  
  888. The controls on the right half of the dialog control paragraph wrapping.
  889. If the "Paragraph Fill" check box is turned off, long lines will be
  890. wrapped, but short lines will be left untouched. If "Paragraph Fill" is
  891. on, the entire contents of the selection range will be rewrapped using
  892. the current width option; no existing line breaks will be preserved.
  893.  
  894. Searching
  895. =========
  896.  
  897. String Searches
  898. ------ --------
  899. BBEdit Lite gives you the ability to search for strings of characters
  900. within the current document, or within multiple files, whether they're
  901. currently open in BBEdit Lite or not. When you choose "Find..." from the
  902. Search menu, BBEdit Lite will present a dialog box with several options.
  903.  
  904. The edit field directly below "Search For:" contains the string of
  905. characters that you wish to search for. If the "Grep" check box is
  906. checked, the string in this edit field is a regular expression. See
  907. below for more information on grep searching.
  908.  
  909. The edit field directly below "Replace With:" contains the string of
  910. characters that will replace the current selection whenever you choose
  911. "Replace", "Replace and Find Again", or "Replace All" from the Search
  912. menu.
  913.  
  914. Note: To search for a carriage return, line feed, or tab character, you
  915. can either 1) type the literal character by holding down the Command key
  916. and hitting the Return or Tab key, or 2) enter the expression "\n" for a
  917. line feed, "\r" for a carriage return, or "\t" for a tab. To search for
  918. a -literal- occurrence of an backslash character "\" (for example, in C
  919. or Rez program source), use two backslashes: "\\n", "\\r", and "\\t".
  920. Also, a "\\" will be interpreted to mean a single backslash (just as it
  921. does in C).
  922.  
  923. The "Match Case" check box determines whether the search is
  924. case-sensitive or not. If "Match Case" is checked, only text which has
  925. the same combination of upper and lower case letters as the Search For
  926. string will be found.
  927.  
  928. The "Entire Word" check box determines whether the text being searched
  929. must be bounded by word breaks (spaces, dashes, and other punctuation).
  930.  
  931. The "Start at Top" check box will cause the entire document to be
  932. searched, starting at the beginning of the document and proceeding
  933. forward to the end of the document.
  934.  
  935. The "Wrap Around" check box will cause the entire document to be
  936. searched, regardless of where the current insertion point or selection
  937. range lies. Ordinarily, only the text from the start of the selection
  938. range to the end of the document is searched. If "Wrap Around" is turned
  939. on, and the search string isn't found between the start of the selection
  940. range and the end of the document, the search will automatically restart
  941. from the beginning of the document. If the search string is found in the
  942. document after wrapping around, BBEdit Lite will blink the menu bar to
  943. alert you.
  944.  
  945. If the "Search Backwards" check box is checked, BBEdit Lite will search
  946. backwards from the start of the insertion point to the start of the
  947. document, rather than forward to the end of the document. If "Wrap
  948. Around" is checked, and the search string is not found between the start
  949. of the document and the start of the selection range, the backwards
  950. search will resume from the end of the document.
  951.  
  952. If the "Selection Only" check box is checked, BBEdit Lite will search
  953. only the selected range of text.
  954.  
  955. Note: If "Start at Top" is checked, the "Search Backwards", "Selection
  956. Only", and "Wrap Around" options are automatically disabled.
  957.  
  958. After you have entered the search and replace strings and set the search
  959. options appropriately, you can click any of the buttons arrayed along
  960. the right-hand edge of the dialog:
  961.  
  962. *   If you click "Find", BBEdit Lite will search for the current search
  963.     string, using the current search options.
  964.  
  965. *   If you click "Find All", BBEdit Lite will locate all occurrences of
  966.     the search string, using the current search options, and display
  967.     those occurrences in a "Search Results" window.
  968.  
  969. *   If you click "Replace", BBEdit Lite will search for the next
  970.     occurrence of the search string, using the current search options,
  971.     and replace it with the specified replace string.
  972.  
  973. *   If you click "Replace All", BBEdit Lite will locate all occurrences
  974.     of the search string, and replace them with the specified replace
  975.     string.
  976.  
  977. *   If you click "Don't Find", BBEdit Lite will accept the current
  978.     search strings and options, but will not perform the search; you can
  979.     then choose "Find Again" from the Search menu to start the search.
  980.  
  981. Note:  If the "Multi-File Search" box is checked, the "Find All" and "Replace 
  982. All" buttons will operate across all files that BBEdit Lite locates using the 
  983. indicated search method and starting point.
  984.  
  985.  
  986. Multi-File Searching
  987. ---------- ---------
  988. BBEdit Lite also provides a variety of means for searching through multiple text 
  989. files at one time in order to locate the search string. To perform a multi-file 
  990. search, check the "Multi-File Search" check box in the Find... dialog.
  991.  
  992. The popup menu next to "What:" determines how BBEdit Lite will locate the 
  993. files to be searched.
  994.  
  995. There are three ways to locate files:
  996.  
  997. *   Folder Search. When this search method is chosen, BBEdit Lite scans
  998.     through the folders starting at the one you choose, and each file
  999.     that it encounters will be searched for the search string.
  1000.  
  1001. *   Open Windows. When you choose this search method, BBEdit Lite
  1002.     searches for the search string only in document windows that are
  1003.     currently open. This sort of search is very fast, and may be most
  1004.     convenient if you wish to limit the scope of your search to a few
  1005.     files.
  1006.  
  1007. *   Search Results. This search method is only available when the
  1008.     "Search Results" window is open and contains the results of a
  1009.     previous Batch Find (see below).
  1010.  
  1011. The check boxes can be used to tailor the search to your needs:
  1012.  
  1013. *   Batch Find accumulates the results of the search in progress and
  1014.     displays them all at once in a Search Results window. If this check
  1015.     box is not checked, then the multi-file search will stop each time
  1016.     it encounters a match, and open the file that contains the match.
  1017.  
  1018. Once the Search Results window is opened, you can single-click on an
  1019. entry in the window to display any given match, or double-click on an
  1020. entry to open the file containing that match.
  1021.  
  1022. *   Search Nested Folders causes the Folder Scan search to search
  1023.     folders which are enclosed in the search's starting directory. If
  1024.     this check box is turned off, only the files in the starting
  1025.     directory will be searched.
  1026.  
  1027. *   Skip (...) Folders causes the Folder Scan to skip folders whose
  1028.     names are enclosed in parentheses. This is useful if you have
  1029.     folders containing text files that you do not want to search for one
  1030.     reason or another; just enclose the folders' names in parentheses,
  1031.     and they will be skipped.
  1032.  
  1033. The "File Type" and "File Name" pop-up menus give you control over the
  1034. types of files that BBEdit Lite will search. Choose "Any File" from the
  1035. menu to search files of all kinds, regardless of whether they contain
  1036. actual text or not. Choose "Text Files" to limit the search to known
  1037. text files.
  1038.  
  1039. When BBEdit Lite performs a multi-file search, it does so in two steps.
  1040. First, it constructs a list of the files to be searched, using the
  1041. search method specified in the Multi-File Search Options dialog. Second,
  1042. it searches each file in the list for the search string. If "Batch Find"
  1043. is selected, all occurrences in each file will be displayed in the
  1044. Search Results window. Otherwise, each file will be opened to display
  1045. the first occurrence of the search string; you can find subsequent
  1046. occurrences of the search string in the same file by choosing "Find
  1047. Again" from the Search menu. If you are not using Batch Find, you can
  1048. locate the next file that contains the search string by choosing "Find
  1049. In Next File" from the Search menu.
  1050.  
  1051. You can combine the capabilities of BBEdit Lite's multi-file search with
  1052. the Replace All command to perform multi-file replace operations. To do
  1053. this, set up a multi-file search as desired, and click the "Replace All"
  1054. button in the Find dialog.
  1055.  
  1056. Once BBEdit Lite has constructed the list of files to search, it will
  1057. present a dialog containing options for the replace operation:
  1058.  
  1059. There are three levels of safety that are available:
  1060.  
  1061. *   Safest. Click on the "Leave Open" radio button. For each file that
  1062.     contains the search string, BBEdit Lite will perform a "Replace All"
  1063.     on that file, and leave the file open so that you can inspect the
  1064.     changes.
  1065.  
  1066. *   Less Safe. Click on the "Save To Disk" radio button, and make sure
  1067.     that the "Confirm Saves" check box is checked. BBEdit Lite will
  1068.     perform a Replace All on each file that contains the search string,
  1069.     and then ask you what to do.
  1070.  
  1071. If you click "Save", BBEdit Lite will save the changed file. If you
  1072. click "Don't Save", BBEdit Lite will throw away the changes that were
  1073. just performed. If you click "Leave Open", BBEdit Lite will leave the
  1074. file open; this is the same behavior as the "Safest" case, above. If you
  1075. click "Cancel Search", BBEdit Lite will stop the multi-file replace
  1076. operation.
  1077.  
  1078. *   Living on the Edge. Click on the "Save to Disk" radio button, and
  1079.     un-check the "Confirm Saves" check box. If you do this, BBEdit Lite
  1080.     will perform a Replace All on each file that contains the search
  1081.     string, and then save the changed file to disk without asking. You
  1082.     should only use these settings if you are absolutely certain of what
  1083.     you are doing, since the changes are irreversible.
  1084.  
  1085.  
  1086. Grep Searching
  1087. ---- ---------
  1088. Grep is a method of pattern matching that derives from utilities
  1089. commonly provided with the Unix(TM) operating system.  You are probably
  1090. familiar with simple pattern matching from using word processors;  when
  1091. you ask a word processor to find all instances of the word "black", it
  1092. is performing a simple pattern match, where each letter has to match
  1093. literally.  Matching strings in this manner is not very hard.
  1094.  
  1095. The ability to match strings in a more general manner is both more
  1096. powerful and more complicated.  It allows for sophisticated pattern
  1097. matching operations, such as matching all words that begin with the
  1098. letter "P" and end with the letters "er", or deleting the first word of
  1099. every line.  Grep provides a powerful means of doing this.
  1100.  
  1101. To use grep patterns for searching documents, just check the "Grep"
  1102. check box in the Find... dialog.
  1103.  
  1104. The popup menu next to the "Patterns:" in the dialog contains a list of
  1105. your most commonly-used grep patterns. You can change this list in the
  1106. "Grep Patterns" section of the Preferences... dialog.
  1107.  
  1108. How Grep Works
  1109.  
  1110. The "grep" mode of searching and replacing is a powerful tool. Although
  1111. somewhat slower than normal text searching, grep allows the user to
  1112. search for one of a set of many strings instead of a particular string.
  1113. As a simple example, you can search for any occurrence of an identifier
  1114. beginning with the letter P, or all lines that begin with a left brace.
  1115.  
  1116. A pattern is a string of characters that, in turn, describes a set of
  1117. strings of characters.  An example of a set of strings is the set of all
  1118. strings that begin with the letter P and end with the letter r;  the
  1119. strings "Ptr" and "ProcPtr" are members of this set.  We say that a
  1120. string is matched by a pattern if it is a member of the set described by
  1121. the pattern.  Patterns are composed of sub- patterns which are patterns
  1122. in themselves;  this is how complicated patterns may be formed.
  1123.  
  1124.  
  1125. Rules for Creating Grep Patterns
  1126.  
  1127. The following section goes through the grep pattern matching and
  1128. replacement rules step by step, so that by the end of it you should be
  1129. able to understand how each of these grep patterns works and be able to
  1130. make your own.
  1131.  
  1132. In some cases, the state of case sensitivity affects the results of a
  1133. pattern match. We have noted below when this is the case.
  1134.  
  1135. 1.  Any character, with certain exceptions described below, is a
  1136.     pattern that matches itself.
  1137.  
  1138. 2.  A pattern x followed by a pattern y forms a pattern xy that
  1139.     matches any string Bu where B can be matched by x and u can be
  1140.     matched by y.  We can, of course, take the compound pattern xy and
  1141.     concatenate yet another pattern z onto it, forming the pattern xyz.
  1142.  
  1143. 3.  The character . is a pattern that will match any character.
  1144.  
  1145. 4.  The character # is a pattern that will match any single numeric
  1146.     digit.
  1147.  
  1148. 5.  The character \ followed by any single character is a pattern which
  1149.     matches the literal single character. (You would use this to
  1150.     find special characters, such as the . or # characters. To search for 
  1151.     a period, you would use \.).
  1152.  
  1153. 6.  A string of characters s surrounded by square brackets ([ and a ])
  1154.     forms a pattern [s] that matches a single instance of one of the
  1155.     characters in the string s.
  1156.  
  1157. 6a. The pattern [^B] matches any character that is not in the string B.
  1158.     Special characters will be taken literally in this context.
  1159.  
  1160. 6b. If a string of three characters in the form [a-b] occurs in the
  1161.     pattern p, this represents all of the characters from a to b
  1162.     inclusive. All special characters are taken literally;  i.e., [!-.]
  1163.     denotes the characters from ! to .. Notice that the only way to
  1164.     include the character ] in p is to make it the very first character.
  1165.     Likewise, the only way to include the character - in p is to have it
  1166.     either at the very beginning or the very end of p.  Single
  1167.     characters and ranges may both be used between brackets.
  1168.  
  1169. 7a. Any pattern p formed by any combination of rules 1 or 3-6b
  1170.     followed by a * forms the pattern p* that matches zero or more
  1171.     consecutive occurrences of characters matched by p.
  1172.  
  1173. 7b. Any pattern p formed by any combination of rules 1 or 3-6b
  1174.     followed by a ? forms the pattern p? that matches zero or one
  1175.     consecutive occurrences of characters matched by p.
  1176.  
  1177. 7c. Any pattern p formed by any combination of rules 1 or 3-6b
  1178.     followed by a + forms the pattern p+ that matches one or more
  1179.     consecutive occurrences of characters matched by p.
  1180.  
  1181. 8.  The character | placed between two patterns p1 and p2 specifies
  1182.     that either one or the other of these patterns (but not both)
  1183.     matches the target string.
  1184.  
  1185. We now have the ability to form patterns that are composed of
  1186. sub-patterns, and will find it useful to "remember" sub-strings matched
  1187. by sub-patterns and to be able to match against those substrings.
  1188.  
  1189. 9.  A pattern surrounded by ( and ) is a pattern that matches whatever
  1190.     the sub-pattern matches.  This is useful when doing replacements.
  1191.  
  1192. Sometimes it is useful to be able to "constrain" patterns to match only if 
  1193. certain conditions in the context outside the string matched are met.
  1194.  
  1195. 10. A pattern p that is preceded by a ^ forms a pattern ^p.  If the
  1196.     pattern ^p is not preceded by any other pattern, it matches whatever
  1197.     p matches as long as the first character matched by p occurs at the
  1198.     beginning of a line.  If the pattern ^p is preceded by another
  1199.     pattern, then the ^ is taken literally.
  1200.  
  1201. 11. A pattern p that is followed by a $ forms a pattern p$.  If the
  1202.     pattern p$ is not followed by any other pattern, it matches whatever
  1203.     p matches as long as the last character matched by p occurs at the
  1204.     end of a line.  If the pattern p$ is followed by another pattern,
  1205.     then the $ is taken literally.
  1206.  
  1207. Note that the characters ^ and $ constrain pattern matches to begin or end 
  1208. at line boundaries, and so can be combined to constrain a pattern to match 
  1209. an entire line only.
  1210.  
  1211. Grep provides not only a more sophisticated method of searching, but a 
  1212. sophisticated method of replacing as well.  In a replacement string, the 
  1213. following substitutions are made before any text replacement occurs:
  1214.  
  1215. 1.  Each occurrence of the character & is replaced with whatever was
  1216.     last matched by the entire pattern.
  1217.  
  1218. 2.  Each occurrence of a string of the form \n, where n is one of the
  1219.     digits 1-9, is replaced by whatever was last matched by the
  1220.     sub-pattern beginning with the nth occurrence of (.
  1221.  
  1222. 3.  Each occurrence of a string of the form \p, where p is other than
  1223.     one of the digits 1-9, is replaced by p.
  1224.  
  1225. This allows you to not only be able to search for a string satisfying a
  1226. complex set of conditions, but also to be able to do a subsequent
  1227. replacement that varies depending on the string that is matched. Note
  1228. that this does not take into account escape sequences, such as \t, \r,
  1229. \n, \\, etc.
  1230.  
  1231. Suppose that you are writing a Macintosh application (i.e., it uses the
  1232. Macintosh ToolBox instead of stdio for the user interface).  Suppose
  1233. also that you have discovered that you have forgotten to put a \p at the
  1234. beginning of your string constants, so that your program is trying to
  1235. pass C strings instead of Pascal strings to the Toolbox (which only
  1236. knows how to deal with Pascal strings).  You can easily change all your
  1237. C strings to Pascal strings by specifying "(.*)" as the search pattern
  1238. and "\\p\1" as the replacement string.
  1239.  
  1240.  
  1241. A Simple Example
  1242.  
  1243. Suppose you decided to reverse the two arguments of the function "foo".
  1244. You might try the pattern foo\(([^,]*),([^)]*)\) as the search pattern
  1245. and foo(\2, \1) as the replacement pattern.  How does the search pattern
  1246. work?
  1247.  
  1248. Let's assume we're trying to match some text that looks like foo(1,*bar)
  1249.  
  1250. foo\(([^,]*),([^)]*)\)  matches foo(1,*bar)
  1251.  
  1252. Since ([^,]*) matched 1 and ([^)]*) matched *bar, the two arguments to
  1253. foo, the replacement pattern foo(\2, \1) will result in foo(*bar, 1)
  1254.  
  1255. This, unfortunately, won't work in the case of foo(1,(*bar)+2), since
  1256. ([^)]*) will match only up to the first right parenthesis, leaving +2)
  1257. unmatched.  If we're sure that all calls to foo end with a semicolon,
  1258. however, we can change our pattern to foo\(([^,]*),([^;]*)\);. In this
  1259. pattern, instead of trying to match the second argument by matching
  1260. everything up to the first right parenthesis, we match everything up to
  1261. the ); which terminates the invocation of foo.
  1262.  
  1263. In this example we showed how to analyze a grep pattern by examining
  1264. sub- patterns. This is a good way of figuring out how to build a pattern
  1265. as well. Grep can be thought of as a small and rather cryptic
  1266. programming language, with each pattern a program and sub-pattern a
  1267. statement in this language. If you try to create a grep pattern by
  1268. testing a small sub-pattern, then adding and testing additional
  1269. sub-patterns until the complete pattern is built, you may find building
  1270. complex grep patterns not nearly as daunting as you first thought.
  1271.  
  1272.  
  1273. An HTML Example
  1274.  
  1275. Using grep, we want to change the following tag instance:
  1276.  
  1277. <CENTER><H2><FONT COLOR=#0000FF>changeable text</FONT></H2></CENTER><P>
  1278.  
  1279. into something that looks like:
  1280.  
  1281. <CENTER><H3><FONT COLOR=#FF00FF>changeable text</FONT></H3></CENTER><P>
  1282.  
  1283. In other words, we want to modify some of the tags, but keep the text
  1284. content the same.
  1285.  
  1286. Here is one way to approach the issue:
  1287.  
  1288. search for:
  1289.  
  1290. <CENTER><H2><FONT COLOR=\#0000FF>([^<]*)</FONT></H2></CENTER><P>
  1291.  
  1292. replace with:
  1293.  
  1294. <CENTER><H3><FONT COLOR=#FF00FF>\1</FONT></H3></CENTER><P>
  1295.  
  1296. (please pay special attention to the parts in bold type during the
  1297. following discussion)
  1298.  
  1299. An important thing to keep in mind when constructing grep patterns is
  1300. that you do not have to abstract everything out; it is OK to use big
  1301. chunks of strings as part of the search pattern!
  1302.  
  1303. In this case, we use strings to specify the exact tag format we want to
  1304. match, and use a character range for the variable text. However, before
  1305. proceeding further, we must see whether these strings contain any
  1306. special grep characters, and if they do, we must modify them
  1307. accordingly.
  1308.  
  1309. In particular, one of the target tags contains a color value  #0000FF,
  1310. and as we learned above, the number sign # is a special character
  1311. meaning 'match any digit' in grep. So, we must _escape_ this in the
  1312. pattern by placing a backslash ahead of it \# so that it will be
  1313. interpreted literally instead. (This is not necessary in the replace
  1314. string, since that is not performing a match on anything, but it would
  1315. work properly there as well.)
  1316.  
  1317. The range is then constructed as follows:  having matched the opening
  1318. font tag by means of a string, we now want to pick up all text from here
  1319. to the next tag. So, we search for anything _except_ another left angle
  1320. bracket [^<] where the range is denoted by the square brackets, ^ means
  1321. "not the following character", and < is of course what would begin the
  1322. next tag. The * added to the range means "find zero or more instances of
  1323. the preceding item" (so we can match empty tags as well), and the whole
  1324. thing is then enclosed in parentheses ([^<]*) to let us reference this
  1325. _subpattern_ in the replace string.
  1326.  
  1327.  
  1328. Thus, the replace string is just the revised tag form, with a  \1  to
  1329. insert the contents of the first (and only) subpattern match defined in
  1330. the search expression at that point.
  1331.  
  1332. A couple of things to keep in mind: this search pattern will not work if
  1333. the 'changeable text' section contains markup, since we are specifically
  1334. keying on the presence of a tag opening character. You can avoid this by
  1335. using the simpler expression:
  1336.  
  1337. search for:
  1338.  
  1339. <CENTER><H2><FONT COLOR=\#0000FF>(.*)</FONT></H2></CENTER><P>
  1340.  
  1341. but this has the disadvantage of not suppressing BBEdit's _longest
  1342. match_ behavior, so any match will extend to the close of the furthest
  1343. font tag possible (e.g. if there are two font tags per line in your
  1344. source document). If all these tags live on single lines, and you have
  1345. markup contained in the changeable text, this is OK; if the tags span
  1346. lines, you are better off with the preceding expression.
  1347.  
  1348.  
  1349. Parting Shots
  1350. ======= =====
  1351.  
  1352. Technical Support
  1353. --------- -------
  1354. Should you have questions about BBEdit Lite, please send us e-mail:
  1355.  
  1356. <support@barebones.com>
  1357.  
  1358. Please note that we cannot provide support for BBEdit Lite or our other
  1359. freeware products via phone or fax.
  1360.  
  1361. From time to time, we will release updates to correct problems in the
  1362. software, and/or add minor functionality. Updates to our freeware may be
  1363. found on the Freeware page on our Web site, as well as in the Freeware
  1364. directory on our public FTP area:
  1365.  
  1366. <ftp://ftp.barebones.com/pub/freeware/>
  1367.  
  1368. We will also provide technical support bulletins, as warranted by
  1369. circumstances, to address some commonly encountered problems. You can
  1370. also find a list of frequently asked questions about BBEdit on our Web
  1371. page.
  1372.  
  1373. If you do have a problem with the software, please let us know. All too
  1374. often, users do not report problems for one reason or another. Remember
  1375. that if we do not hear about a problem, we can't fix it.
  1376.  
  1377. Copyrights
  1378. ----------
  1379. All products mentioned are trademarks or registered trademarks of their
  1380. respective holders.
  1381.  
  1382. This document is written by and copyright (c)1995-1998 by Bare Bones
  1383. Software, Inc. It may be redistributed freely as long as it is not
  1384. modified in any way. Information presented here is accurate as of the
  1385. time of writing, but is subject to change without notice.
  1386.  
  1387. BBEdit Lite is copyright (c)1992-1998 Bare Bones Software, Inc., all
  1388. rights reserved. Please see the preceding section of this document for
  1389. license requirements.
  1390.  
  1391.  
  1392. Limited warranty and limitation of remedies
  1393. ------- -------- --- ---------- -- --------
  1394. The program and any support from Bare Bones Software, Inc., are provided
  1395. "as is" and without warranty, express and implied, including but not
  1396. limited to any implied warranties of merchantability and fitness for a
  1397. particular purpose.  In no event will Bare Bones Software, Inc. be
  1398. liable for any damages, including lost profits, lost savings, or other
  1399. incidental or consequential damages, even if Bare Bones Software, Inc.
  1400. is advised of the possibility of such damages, or for any claim by you
  1401. or any third party.
  1402.  
  1403.  
  1404. Additional Acknowledgements
  1405. ---------- ----------------
  1406. The regular-expression library used for 'grep' searching is based on the
  1407. 'regexp' package, written by Henry Spencer of the University of Toronto.
  1408. Pete Keleher provided a Mac- compatible version, from which BBEdit's
  1409. code is derived.
  1410.  
  1411.  
  1412. Thanks!
  1413. =======
  1414. Thank you for using BBEdit Lite! If you have any suggestions for
  1415. improvements, or any problems to report, please do not be shy. Our
  1416. experience shows that feedback from our customers has consistently led
  1417. to better products and happier users.
  1418.  
  1419.  
  1420.   -- The Bare Bones Software Team
  1421.  
  1422.  
  1423.  
  1424. =end=
  1425.